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1. Introduction 


This document provides an architectural framework for datastores as 
they are used by network management protocols such as the Network 
Configuration Protocol (NETCONF) [RFC6241], RESTCONF [RFC8040], and 
the YANG data modeling language [RFC7950]. Datastores are a 
fundamental concept binding network management data models to network 
management protocols. Agreement on a common architectural model of 
datastores ensures that data models can be written in a way that is 
network management protocol agnostic. This architectural framework 
identifies a set of conceptual datastores, but it does not mandate 
that all network management protocols expose all these conceptual 
datastores. This architecture is agnostic with regard to the 
encoding used by network management protocols. 


This document updates RFC 7950 by refining the definition of the 
accessible tree for some XML Path Language (XPath) context (see 
Section 6.1) and the invocation context of operations (see 
Section 6.2). 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 
"OPTIONAL" in this document are to be interpreted as described in 
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 
capitals, as shown here. 
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2. Objectives 


Network management data objects can often take two different values: 
the value configured by the user or an application (configuration) 
and the value that the device is actually using (operational state). 
These two values may be different for a number of reasons, e.g., 
system internal interactions with hardware, interaction with 
protocols or other devices, or simply the time it takes to propagate 
a configuration change to the software and hardware components of a 
system. Furthermore, configuration and operational state data 
objects may have different lifetimes. 


The original model of datastores required these data objects to be 
modeled twice in the YANG schema -- as "config true" objects and as 
"config false" objects. The convention adopted by the interfaces 
data model [RFC8343] and the IP data model [RFC8344] was to use two 
separate branches rooted at the root of the data tree: one branch for 
configuration data objects and one branch for operational state data 
objects. 


The duplication of definitions and the ad hoc separation of 
operational state data from configuration data lead to a number of 
problems. Having configuration and operational state data in 
separate branches in the data model is operationally complicated and 
impacts the readability of module definitions. Furthermore, the 
relationship between the branches is not machine readable, and filter 
expressions operating on configuration and on related operational 
state are different. 


With the revised architectural model of datastores defined in this 
document, the data objects are defined only once in the YANG schema 
but independent instantiations can appear in different datastores, 
e.g., one for a configured value and another for an operationally 
used value. This provides a more elegant and simpler solution to the 
problem. 


The revised architectural model of datastores supports additional 
datastores for systems that support more advanced processing chains 
converting configuration to operational state. For example, some 
systems support configuration that is not currently used (so-called 
"inactive configuration") or they support configuration templates 
that are used to expand configuration data via a common template. 
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3- 


Terminology 


This document defines the following terminology. Some of the terms 
are revised definitions of terms originally defined in [RFC6241] and 
[RFC7950] (see also Section 4). The revised definitions are 
semantically equivalent to the definitions found in [RFC6241] and 
[RFC7950]. It is expected that the revised definitions provided in 
this section will replace the definitions in [RFC6241] and [RFC7950] 
when these documents are revised. 


o datastore: A conceptual place to store and access information. A 
datastore might be implemented, for example, using files, a 
database, flash memory locations, or combinations thereof. A 
datastore maps to an instantiated YANG data tree. 


o schema node: A node in the schema tree. The formal definition is 
provided in RFC 7950. 


o datastore schema: The combined set of schema nodes for all modules 
supported by a particular datastore, taking into consideration any 
deviations and enabled features for that datastore. 


o configuration: Data that is required to get a device from its 
initial default state into a desired operational state. This data 
is modeled in YANG using "config true" nodes. Configuration can 
originate from different sources. 


o configuration datastore: A datastore holding configuration. 


o running configuration datastore: A configuration datastore holding 
the current configuration of the device. It may include 
configuration that requires further transformations before it can 
be applied. This datastore is referred to as "<running>". 


o candidate configuration datastore: A configuration datastore that 
can be manipulated without impacting the device’s running 
configuration datastore and that can be committed to the running 
configuration datastore. This datastore is referred to as 
"<candidate>". 


o startup configuration datastore: A configuration datastore holding 
the configuration loaded by the device into the running 
configuration datastore when it boots. This datastore is referred 
to as "<startup>". 
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o intended configuration: Configuration that is intended to be used 
by the device. It represents the configuration after all 
configuration transformations to <running> have been performed and 
is the configuration that the system attempts to apply. 


o intended configuration datastore: A configuration datastore 
holding the complete intended configuration of the device. This 
datastore is referred to as "<intended>". 


o configuration transformation: The addition, modification, or 
removal of configuration between the <running> and <intended> 
datastores. Examples of configuration transformations include the 
removal of inactive configuration and the configuration produced 
through the expansion of templates. 


o conventional configuration datastore: One of the following set of 
configuration datastores: <running>, <startup>, <candidate>, and 
<intended>. These datastores share a common datastore schema, and 
protocol operations allow copying data between these datastores. 
The term "conventional" is chosen as a generic umbrella term for 
these datastores. 


o conventional configuration: Configuration that is stored in any of 
the conventional configuration datastores. 


o dynamic configuration datastore: A configuration datastore holding 
configuration obtained dynamically during the operation of a 
device through interaction with other systems, rather than through 
one of the conventional configuration datastores. 


o dynamic configuration: Configuration obtained via a dynamic 
configuration datastore. 


o learned configuration: Configuration that has been learned via 
protocol interactions with other systems and that is neither 
conventional nor dynamic configuration. 


o system configuration: Configuration that is supplied by the device 
itself. 


o default configuration: Configuration that is not explicitly 
provided but for which a value defined in the data model is used. 


o applied configuration: Configuration that is actively in use by a 


device. Applied configuration originates from conventional, 
dynamic, learned, system, and default configuration. 
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o system state: The additional data on a system that is not 
configuration, such as read-only status information and collected 
statistics. System state is transient and modified by 
interactions with internal components or other systems. System 
state is modeled in YANG using "config false" nodes. 


Oo operational state: The combination of applied configuration and 
system state. 


O operational state datastore: A datastore holding the complete 
operational state of the device. This datastore is referred to as 
"<operational>". 


o origin: A metadata annotation indicating the origin of a 
data item. 


o remnant configuration: Configuration that remains part of the 
applied configuration for a period of time after it has been 
removed from the intended configuration or dynamic configuration. 
The time period may be minimal or may last until all resources 
used by the newly deleted configuration (e.g., network 
connections, memory allocations, file handles) have been 
deallocated. 


The following additional terms are not datastore specific, but they 
are commonly used and are thus defined here as well: 


o client: An entity that can access YANG-defined data on a server, 
over some network management protocol. 


o server: An entity that provides access to YANG-defined data to a 
client, over some network management protocol. 


o notification: A server-initiated message indicating that a certain 
event has been recognized by the server. 


o remote procedure call: An operation that can be invoked by a 
client on a server. 
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4. Background 
NETCONF [RFC6241] provides the following definitions: 


o datastore: A conceptual place to store and access information. A 
datastore might be implemented, for example, using files, a 
database, flash memory locations, or combinations thereof. 


o configuration datastore: The datastore holding the complete set of 
configuration that is required to get a device from its initial 
default state into a desired operational state. 


YANG 1.1 [RFC7950] provides the following refinements when NETCONF is 
used with YANG (which is the usual case, but note that NETCONF was 
defined before YANG existed): 


o datastore: When modeled with YANG, a datastore is realized as an 
instantiated data tree. 


o configuration datastore: When modeled with YANG, a configuration 
datastore is realized as an instantiated data tree with 
configuration. 


[RFC6244] defined operational state data as follows: 


o Operational state data is a set of data that has been obtained by 
the system at runtime and influences the system’s behavior similar 
to configuration data. In contrast to configuration data, 
operational state is transient and modified by interactions with 
internal components or other systems via specialized protocols. 


Section 4.3.3 of [RFC6244] discusses operational state and mentions, 
among other things, the option to consider operational state as being 
stored in another datastore. Section 4.4 of [RFC6244] then concludes 
that, at the time of its writing, modeling state as distinct leafs 
and distinct branches is the recommended approach. 


Implementation experience and requests from operators [OpState-Regs] 
[OpState-Modeling] indicate that the datastore model initially 
designed for NETCONF and refined by YANG needs to be extended. In 
particular, the notion of intended configuration and applied 
configuration has developed. 
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4.1. Original Model of Datastores 


The following drawing shows the original model of datastores as it is 
currently used by NETCONF [RFC6241]: 


Se E ee PSOE + +----------- + 
| <candidate> | | <startup> | 
| (ct, rw) | <---+ +---> | (ct, rw) | 
+------------- + +----------- + 
| | 
| +----------- + | 
+-------—- >| <running> |<-------- + 
| (ct, rw) | 
pette nnn + 
| 
v 
operational state <--- control plane 
(cf, ro) 
ct = config true; cf = config false 


rw = read-write; ro = read-only 
boxes denote datastores 


Figure 1 
Note that this diagram simplifies the model: "read-only" (ro) and 
"read-write" (rw) are to be understood from the client’s perspective, 


at a conceptual level. In NETCONF, for example, support for 
<candidate> and <startup> is optional, and <running> does not have to 
be writable. Furthermore, <startup> can only be modified by copying 
<running> to <startup> in the standardized NETCONF datastore editing 
model. The RESTCONF protocol does not expose these differences and 
instead provides only a writable unified datastore, which hides 
whether edits are done through <candidate>, by directly modifying 
<running>, or via some other implementation-specific mechanism. 
RESTCONF also hides how configuration is made persistent. Note that 
implementations may also have additional datastores that can 
propagate changes to <running>. NETCONF explicitly mentions 
so-called "named datastores". 
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Some observations: 


o Operational state has not been defined as a datastore, although 
there were proposals in the past to introduce an operational state 
datastore. 


o The NETCONF <get> operation returns the contents of <running> 
together with the operational state. It is therefore necessary 
that "config false" data be in a different branch than the 
"config true" data if the operational state can have a different 
lifetime compared to configuration or if configuration is not 
immediately or successfully applied. 


o Several implementations have proprietary mechanisms that allow 
clients to store inactive data in <running>. Inactive data is 
conceptually removed before validation. 


o Some implementations have proprietary mechanisms that allow 
clients to define configuration templates in <running>. These 
templates are expanded automatically by the system, and the 
resulting configuration is applied internally. 


o Some operators have reported that it is essential for them to be 
able to retrieve the configuration that has actually been 
successfully applied, which may be a subset or a superset of the 
<running> configuration. 
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5. Architectural Model of Datastores 


Below is a new conceptual model of datastores, 


March 2018 


extending the original 


model in order to reflect the experience gained with the original 


model. 
+------------- + +=========== + 
| <candidate> | | <startup> | 
| (ct, rw) |<---+ +---> | (ct, rw) | 
+------------—- + | | +----------- + 
| | 
| fers | 
+——-—-—-=-= >| <running> |<-------- + 
| (ct, rw) | 
+----------- + 
// configuration transformations, 
| // e.g., removal of nodes marked as 
| // "inactive", expansion of 
| // templates 
v 
+============ + 
| <intended> | // subject to validation 
| (ct, ro) | 
4+------------ + 
| // changes applied, subject to 
| // local factors, e.g., missing 
// resources, delays 
dynamic | +-------- learned configuration 
configuration | pasts system configuration 
datastores ----- i | i Poor default configuration 
v v v 
+--------------- + 
| <operational> | <-- system state 
| (ct + cf, ro) | 
4+--------------- + 
ct = config true; cf = config false 
rw = read-write; ro = read-only 
boxes denote named datastores 
Figure 2 
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5.1. Conventional Configuration Datastores 


The conventional configuration datastores are a set of configuration 
datastores that share exactly the same datastore schema, allowing 
data to be copied between them. The term is meant as a generic 
umbrella description of these datastores. If a module does not 
contain any configuration data nodes and it is not needed to satisfy 
any imports, then it MAY be omitted from the datastore schema for the 
conventional configuration datastores. The set of datastores 
include: 


o <running> 

o <candidate> 
o <startup> 

o <intended> 


Other conventional configuration datastores may be defined in future 
documents. 


The flow of data between these datastores is depicted in Section 5. 


The specific protocols may define explicit operations to copy between 
these datastores, e.g., NETCONF defines the <copy-config> operation. 


5.1.1. The Startup Configuration Datastore (<startup>) 


The startup configuration datastore (<startup>) is a configuration 
datastore holding the configuration loaded by the device when it 
boots. <startup> is only present on devices that separate the 
startup configuration from the running configuration datastore. 


The startup configuration datastore may not be supported by all 
protocols or implementations. 


On devices that support non-volatile storage, the contents of 
<startup> will typically persist across reboots via that storage. At 
boot time, the device loads the saved startup configuration into 
<running>. To save a new startup configuration, data is copied to 
<startup> via either implicit or explicit protocol operations. 
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5.1.2. The Candidate Configuration Datastore (<candidate>) 


The candidate configuration datastore (<candidate>) is a 
configuration datastore that can be manipulated without impacting the 
device’s current configuration and that can be committed to 
<running>. 


The candidate configuration datastore may not be supported by all 
protocols or implementations. 


<candidate> does not typically persist across reboots, even in the 


presence of non-volatile storage. If <candidate> is stored using 
non-volatile storage, it is reset at boot time to the contents of 
<running>. 

5.1.3. The Running Configuration Datastore (<running>) 


The running configuration datastore (<running>) is a configuration 
datastore that holds the current configuration of the device. It MAY 
include configuration that requires further transformation before it 
can be applied, e.g., inactive configuration, or template-mechanism- 
oriented configuration that needs further expansion. However, 
<running> MUST always be a valid configuration data tree, as defined 
in Section 8.1 of [RFC7950]. 


<running> MUST be supported if the device can be configured via 
conventional configuration datastores. 


If a device does not have a distinct <startup> and non-volatile 
storage is available, the device will typically use that non-volatile 
storage to allow <running> to persist across reboots. 


5.1.4. The Intended Configuration Datastore (<intended>) 


The intended configuration datastore (<intended>) is a read-only 
configuration datastore. It represents the configuration after all 
configuration transformations to <running> are performed (e.g., 
template expansion, removal of inactive configuration) and is the 
configuration that the system attempts to apply. 


<intended> is tightly coupled to <running>. Whenever data is written 
to <running>, the server MUST also immediately update and validate 
<intended>. 


<intended> MAY also be updated independently of <running> if the 
effect of a configuration transformation changes, but <intended> MUST 
always be a valid configuration data tree, as defined in Section 8.1 
of [RFC7950]. 
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For simple implementations, <running> and <intended> are identical. 


The contents of <intended> are also related to the "config true" 
subset of <operational>; hence, a client can determine to what extent 
the intended configuration is currently in use by checking to see 
whether the contents of <intended> also appear in <operational>. 


<intended> does not persist across reboots; its relationship with 
<running> makes that unnecessary. 


Currently, there are no standard mechanisms defined that affect 
<intended> so that it would have different content than <running>, 
but this architecture allows for such mechanisms to be defined. 


One example of such a mechanism is support for marking nodes as 
inactive in <running>. Inactive nodes are not copied to <intended>. 
A second example is support for templates, which can perform 
transformations on the configuration from <running> to the 
configuration written to <intended>. 


5.2. Dynamic Configuration Datastores 


The model recognizes the need for dynamic configuration datastores 
that are, by definition, not part of the persistent configuration of 
a device. In some contexts, these have been termed "ephemeral 
datastores", since the information is ephemeral, i.e., lost upon 
reboot. The dynamic configuration datastores interact with the rest 
of the system through <operational>. 


The datastore schema for a dynamic configuration datastore MAY differ 
from the datastore schema used for conventional configuration 
datastores. If a module does not contain any configuration data 
nodes and it is not needed to satisfy any imports, then it MAY be 
omitted from the datastore schema for the dynamic configuration 
datastore. 


5.3. The Operational State Datastore (<operational>) 


The operational state datastore (<operational>) is a read-only 
datastore that consists of all "config true" and "config false" nodes 
defined in the datastore’s schema. In the original NETCONF model, 
the operational state only had "config false" nodes. The reason for 
incorporating "config true" nodes here is to be able to expose all 
operational settings without having to replicate definitions in the 
data models. 
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<operational> contains system state and all configuration actually 
used by the system. This includes all applied configuration from 
<intended>, learned configuration, system-provided configuration, and 
default values defined by any supported data models. In addition, 
<operational> also contains applied configuration from dynamic 
configuration datastores. 


The datastore schema for <operational> MUST be a superset of the 
combined datastore schema used in all configuration datastores, 
except that configuration data nodes supported in a configuration 
datastore MAY be omitted from <operational> if a server is not able 
to accurately report them. 


Requests to retrieve nodes from <operational> always return the value 
in use if the node exists, regardless of any default value specified 
in the YANG module. If no value is returned for a given node, then 
this implies that the node is not used by the device. 


The interpretation of what constitutes being "in use" by the system 
is dependent on both the schema definition and the device 
implementation. Generally, functionality that is enabled and 
operational on the system would be considered to be "in use". 
Conversely, functionality that is neither enabled nor operational on 
the system is considered not to be "in use"; hence, it SHOULD be 
omitted from <operational>. 


<operational> SHOULD conform to any constraints specified in the data 
model, but given the principal aim of returning "in use" values, it 
is possible that constraints MAY be violated under some circumstances 
(e.g., an abnormal value is "in use", the structure of a list is 
being modified, or remnant configuration (see Section 5.3.1) still 


exists). Note that deviations SHOULD be used when it is known in 
advance that a device does not fully conform to the <operational> 
schema. 


Only semantic constraints MAY be violated. These are the YANG 
"when", "must", "mandatory", "unique", "min-elements", and 
"max-elements" statements; and the uniqueness of key values. 


Syntactic constraints MUST NOT be violated, including hierarchical 
organization, identifiers, and type-based constraints. If a node in 
<operational> does not meet the syntactic constraints, then it 

MUST NOT be returned, and some other mechanism should be used to flag 
the error. 


<operational> does not persist across reboots. 
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5.3.1. Remnant Configuration 


Changes to configuration may take time to percolate through to 
<operational>. During this period, <operational> may contain nodes 
for both the previous and current configuration, as closely as 
possible tracking the current operation of the device. Such remnant 
configuration from the previous configuration persists until the 
system has released resources used by the newly deleted configuration 
(e.g., network connections, memory allocations, file handles). 


Remnant configuration is a common example of where the semantic 
constraints defined in the data model cannot be relied upon for 
<operational>, since the system may have remnant configuration whose 
constraints were valid with the previous configuration and that are 
not valid with the current configuration. Since constraints on 
"config false" nodes may refer to "config true" nodes, remnant 
configuration may force the violation of those constraints. 


5.3.2. Missing Resources 


Configuration in <intended> can refer to resources that are not 
available or otherwise not physically present. In these situations, 
these parts of <intended> are not applied. The data appears in 
<intended> but does not appear in <operational>. 


A typical example is an interface configuration that refers to an 
interface that is not currently present. In such a situation, the 
interface configuration remains in <intended> but the interface 
configuration will not appear in <operational>. 


Note that configuration validity cannot depend on the current state 
of such resources, since that would imply that removing a resource 
might render the configuration invalid. This is unacceptable, 
especially given that rebooting such a device would cause it to 
restart with an invalid configuration. Instead, we allow 
configuration for missing resources to exist in <running> and 
<intended>, but it will not appear in <operational>. 


5.3.3. System-Controlled Resources 


Sometimes, resources are controlled by the device and the 
corresponding system-controlled data appears in (and disappears from) 
<operational> dynamically. If a system-controlled resource has 
matching configuration in <intended> when it appears, the system will 
try to apply the configuration; this causes the configuration to 
appear in <operational> eventually (if application of the 
configuration was successful). 
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5.3.4. Origin Metadata Annotation 


As configuration flows into <operational>, it is conceptually marked 
with a metadata annotation [RFC7952] that indicates its origin. The 
origin applies to all configuration nodes except non-presence 
containers. The "origin" metadata annotation is defined in 

Section 7. The values are YANG identities. The following identities 
are defined: 


o origin: abstract base identity from which the other origin 
identities are derived. 


o intended: represents configuration provided by <intended>. 


o dynamic: represents configuration provided by a dynamic 
configuration datastore. 


o system: represents configuration provided by the system itself. 
Examples of system configuration include applied configuration for 
an always-existing loopback interface, or interface configuration 
that is auto-created due to the hardware currently present in the 
device. 


o learned: represents configuration that has been learned via 
protocol interactions with other systems, including such protocols 
as link-layer negotiations, routing protocols, and DHCP. 


o default: represents configuration using a default value specified 
in the data model, using either values in the "default" statement 
or any values described in the "description" statement. The 
default origin is only used when the configuration has not been 
provided by any other source. 


o unknown: represents configuration for which the system cannot 
identify the origin. 


These identities can be further refined, e.g., there could be 
separate identities for particular types or instances of dynamic 
configuration datastores derived from "dynamic". 


For all configuration data nodes in <operational>, the device SHOULD 


report the origin that most accurately reflects the source of the 
configuration that is in use by the system. 
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In cases where it could be ambiguous as to which origin should be 
used, i.e., where the same data node value has originated from 
multiple sources, the "description" statement in the YANG module 
SHOULD be used as guidance for choosing the appropriate origin. For 
example: 


Lf, 


for a particular configuration node, the associated YANG 


"description" statement indicates that a protocol-negotiated value 
overrides any configured value, then the origin would be reported as 
"learned", even when a learned value is the same as the configured 
value. 


Conversely, if, for a particular configuration node, the associated 
YANG "description" statement indicates that a protocol-negotiated 
value does not override an explicitly configured value, then the 
origin would be reported as "intended", even when a learned value is 
the same as the configured value. 


In the case that a device cannot provide an accurate origin for a 
particular configuration data node, it SHOULD use the origin 
"unknown". 


6. 


bala 


Implications on YANG 


XPath Context 


This section updates Section 6.4.1 of RFC 7950. 


If a server implements the architecture defined in this document, the 
accessible trees for some XPath contexts are refined as follows: 


[0] 


If the XPath expression is defined in a substatement to a data 
node that represents system state, the accessible tree is all 
operational state in the server. The root node has all top-level 
data nodes in all modules as children. 


If the XPath expression is defined in a substatement to a 
"notification" statement, the accessible tree is the notification 
instance and all operational state in the server. If the 
notification is defined on the top level in a module, then the 
root node has the node representing the notification being defined 
and all top-level data nodes in all modules as children. 
Otherwise, the root node has all top-level data nodes in all 
modules as children. 
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o If the XPath expression is defined in a substatement to an "input" 
statement in an "rpc" or "action" statement, the accessible tree 
is the RPC or action operation instance and all operational state 
in the server. The root node has top-level data nodes in all 
modules as children. Additionally, for an RPC, the root node also 
has the node representing the RPC operation being defined as a 
child. The node representing the operation being defined has the 
operation’s input parameters as children. 


o If the XPath expression is defined in a substatement to an 
"output" statement in an "rpc" or "action" statement, the 
accessible tree is the RPC or action operation instance and all 
operational state in the server. The root node has top-level data 
nodes in all modules as children. Additionally, for an RPC, the 
root node also has the node representing the RPC operation being 
defined as a child. The node representing the operation being 
defined has the operation’s output parameters as children. 


6.2. Invocation of Actions and RPCs 
This section updates Section 7.15 of RFC 7950. 
Actions are always invoked in the context of the operational state 
datastore. The node for which the action is invoked MUST exist in 
the operational state datastore. 
Note that this document does not constrain the result of invoking an 


RPC or action in any way. For example, an RPC might be defined to 
modify the contents of some datastore. 
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7. YANG Modules 
<CODE BEGINS> file "ietf-datastores@2018-02-14.yang" 


module ietf-datastores { 
yang-version 1.1; 
namespace "urn:ietf:params:xml:ns:yang:ietf-datastores"; 
prefix ds; 


organization 
"TETF Network Modeling (NETMOD) Working Group"; 


contact 
"WG Web: <https://datatracker.ietf.org/wg/netmod/> 


WG List: <mailto:netmod@ietf.org> 


Author: Martin Bjorklund 
<mailto:mbj@tail-f.com> 


Author: Juergen Schoenwaelder 
<mailto:j.schoenwaelder@jacobs-university.de> 


Author: Phil Shafer 
<mailto:phil@juniper.net> 


Author: Kent Watsen 
<mailto:kwatsen@juniper.net> 


Author: Rob Wilton 
<rwilton@cisco.com>"; 


description 
"This YANG module defines a set of identities for identifying 
datastores. 


Copyright (c) 2018 IETF Trust and the persons identified as 
authors of the code. All rights reserved. 


Redistribution and use in source and binary forms, with or 
without modification, is permitted pursuant to, and subject to 
the license terms contained in, the Simplified BSD License set 
forth in Section 4.c of the IETF Trust’s Legal Provisions 
Relating to IETF Documents 
(https://trustee.ietf.org/license-info). 
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This version of this YANG module is part of RFC 8342 
(https://www.rfc-editor.org/info/rfc8342); see the RFC itself 
for full legal notices."; 


revision 2018-02-14 { 
description 
"Tnitial revision."; 
reference 
"RFC 8342: Network Management Datastore Architecture (NMDA)"; 
} 


/* 
* Identities 


xy 


identity datastore { 
description 
"Abstract base identity for datastore identities."; 


} 


identity conventional { 
base datastore; 
description 
"Abstract base identity for conventional configuration 
datastores."; 


} 


identity running { 
base conventional; 
description 
"The running configuration datastore."; 


} 


identity candidate ( 
base conventional; 
description 
"The candidate configuration datastore."; 


} 


identity startup { 
base conventional; 
description 
"The startup configuration datastore."; 
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identity intended { 
base conventional; 
description 
"The intended configuration datastore."; 


} 


identity dynamic { 
base datastore; 
description 
"Abstract base identity for dynamic configuration datastores."; 


} 


identity operational { 
base datastore; 
description 
"The operational state datastore."; 


} 
/* 


* Type definitions 


ae 


typedef datastore-ref { 
type identityref { 
base datastore; 
} 
description 
"A datastore identity reference."; 


<CODE ENDS> 
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<CODE BEGINS> file "ietf-origin@2018-02-14.yang" 


module ietf-origin { 
yang-version 1.1; 
namespace "urn:ietf:params:xml:ns:yang:ietf-origin"; 
prefix or; 


import ietf-yang-metadata { 
prefix md; 


} 


organization 
"TETF Network Modeling (NETMOD) Working Group"; 


contact 
"WG Web: <https://datatracker.ietf.org/wg/netmod/> 


WG List: <mailto:netmod@ietf.org> 


Author: Martin Bjorklund 
<mailto:mbj@tail-f.com> 


Author: Juergen Schoenwaelder 
<mailto:j.schoenwaelder@jacobs-university.de> 


Author: Phil Shafer 
<mailto:phil@juniper.net> 


Author: Kent Watsen 
<mailto:kwatsen@juniper.net> 


Author: Rob Wilton 
<rwilton@cisco.com>"; 


description 
"This YANG module defines an ”origin” metadata annotation and a 
set of identities for the origin value. 


Copyright (c) 2018 IETF Trust and the persons identified as 
authors of the code. All rights reserved. 


Redistribution and use in source and binary forms, with or 
without modification, is permitted pursuant to, and subject to 
the license terms contained in, the Simplified BSD License set 
forth in Section 4.c of the IETF Trust’s Legal Provisions 
Relating to IETF Documents 
(https://trustee.ietf.org/license-info). 
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This version of this YANG module is part of RFC 8342 
(https://www.rfc-editor.org/info/rfc8342); see the RFC itself 
for full legal notices."; 


revision 2018-02-14 { 
description 
"Tnitial revision."; 
reference 
"RFC 8342: Network Management Datastore Architecture (NMDA)"; 
} 


/* 
* Identities 


xy 


identity origin { 
description 
"Abstract base identity for the origin annotation."; 


} 


identity intended { 
base origin; 
description 
"Denotes configuration from the intended configuration 
datastore."; 


} 


identity dynamic { 
base origin; 
description 
"Denotes configuration from a dynamic configuration 
datastore."; 


} 


identity system { 
base origin; 
description 
"Denotes configuration originated by the system itself. 


Examples of system configuration include applied configuration 
for an always-existing loopback interface, or interface 
configuration that is auto-created due to the hardware 
currently present in the device."; 
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identity learned { 
base origin; 
description 
"Denotes configuration learned from protocol interactions with 
other devices, instead of via either the intended 
configuration datastore or any dynamic configuration 
datastore. 


Examples of protocols that provide learned configuration 
include link-layer negotiations, routing protocols, and 
DHCP."; 

} 


identity default { 
base origin; 
description 
"Denotes configuration that does not have a configured or 
learned value but has a default value in use. Covers both 
values defined in a ”default” statement and values defined 
via an explanation in a ”description” statement."; 


} 


identity unknown { 
base origin; 
description 
"Denotes configuration for which the system cannot identify the 
origin"; 


) 
/* 


* Type definitions 


Kf 


typedef origin-ref ( 
type identityref { 
base origin; 
} 
description 
"An origin identity reference."; 
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/* 
* Metadata annotations 
KN 


md:annotation origin { 
type origin-ref; 
description 
"The ‘origin’ 
data node in the operational 


from where the node originated. 


configuration data node, 
origin of its parent node in 


March 2018 


annotation can be present on any configuration 


state datastore. It specifies 


If not specified for a given 


then the origin is the same as the 


the data tree. The origin for 


any top-level configuration data nodes must be specified."; 


} 


<CODE ENDS> 


the following 


8. IANA Considerations 
8.1. Updates to the IETF XML Registry 
This document registers two URIs in the "IETF XML Registry" 
[RFC3688]. Following the format in [RFC3688], 
registrations have been made: 
URI: urn:ietf:params:xml:ns:yang:ietf—-datastores 
Registrant Contact: The IESG. 
XML: N/A; the requested URI is an XML namespace. 
URI: urn:ietf:params:xml:ns:yang:ietf-origin 
Registrant Contact: The IESG. 
XML: N/A; the requested URI is an XML namespace. 
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8.2. Updates to the YANG Module Names Registry 


This document registers two YANG modules in the "YANG Module Names" 
registry [RFC6020]. Following the format in [RFC6020], the following 
registrations have been made: 


name: ietf-datastores 
namespace: urn:ietf:params:xmlins:yang:ietf-datastores 
prefix: ds 
reference: RFC 8342 
name: ietf-origin 
namespace: urn:ietf:params:xml:ns:yang:ietf-origin 
prefix: or 
reference: RFC 8342 
9. Security Considerations 


This document discusses an architectural model of datastores for 
network management using NETCONF/RESTCONF and YANG. It has no 
security impact on the Internet. 


Although this document specifies several YANG modules, these modules 
only define identities and a metadata annotation; hence, the "YANG 
module security guidelines" [YANG-SEC] do not apply. 


The origin metadata annotation exposes the origin of values in the 
applied configuration. Origin information may provide hints that 
certain control-plane protocols are active on a device. Since origin 
information is tied to applied configuration values, it is only 
accessible to clients that have the permissions to read the applied 


configuration values. Security administrators should consider the 
sensitivity of origin information while defining access control 
rules. 
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Appendix A. Guidelines for Defining Datastores 


The definition of a new datastore in this architecture should be 
provided in a document (e.g., an RFC) purposed for defining the 
datastore. When it makes sense, more than one datastore may be 
defined in the same document (e.g., when the datastores are logically 
connected). Each datastore’s definition should address the points 
specified in the subsections below. 


A.1. Define Which YANG Modules Can Be Used in the Datastore 


Not all YANG modules may be used in all datastores. Some datastores 
may constrain which data models can be used in them. If it is 
desirable that a subset of all modules can be targeted to the 
datastore, then the documentation defining the datastore must 
indicate this. 


A.2. Define Which Subset of YANG-Modeled Data Applies 


By default, the data in a datastore is modeled by all YANG statements 
in the available YANG modules. However, it is possible to specify 
criteria that YANG statements must satisfy in order to be present in 
a datastore. For instance, maybe only "config true" nodes, or 
"config false" nodes that also have a specific YANG extension, are 
present in the datastore. 


A.3. Define How Data Is Actualized 


The new datastore must specify how it interacts with other 
datastores. 


For example, the diagram in Section 5 depicts dynamic configuration 
datastores feeding into <operational>. How this interaction occurs 
has to be defined by the particular dynamic configuration datastores. 
In some cases, it may occur implicitly, as soon as the data is put 
into the dynamic configuration datastore, while in other cases an 
explicit action (e.g., an RPC) may be required to trigger the 
application of the datastore’s data. 


A.4. Define Which Protocols Can Be Used 


By default, it is assumed that both the NETCONF and RESTCONF 
protocols can be used to interact with a datastore. However, it may 
be that only a specific protocol can be used (e.g., Forwarding and 
Control Element Separation (ForCES)) or that a subset of all protocol 
operations or capabilities are available (e.g., no locking or no 
XPath-based filtering). 
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A.5. Define YANG Identities for the Datastore 


The datastore must be defined with a YANG identity that uses the 
"ds:datastore" identity, or one of its derived identities, as its 
base. This identity is necessary, so that the datastore can be 
referenced in protocol operations (e.g., <get-data>). 


The datastore may also be defined with an identity that uses the 
"or:origin" identity, or one of its derived identities, as its base. 
This identity is needed if the datastore interacts with 
<operational>, so that data originating from the datastore can be 
identified as such via the "origin" metadata attribute defined in 
Section 7. 


An example of these guidelines in use is provided in Appendix B. 
Appendix B. Example of an Ephemeral Dynamic Configuration Datastore 


This section defines documentation for an example dynamic 
configuration datastore using the guidelines provided in Appendix A. 
For brevity, only a terse example is provided; it is expected that a 
standalone RFC would be written when this type of scenario is fully 
considered. 


This example defines a dynamic configuration datastore called 
"ephemeral", which is loosely modeled after the work done in the I2RS 
Working Group. 


+==================== +============================================== + 
| Name | Value | 
4+-------------------- +============================================== + 
| Name | ephemeral | 
| | | 
| YANG modules | all (default) | 
| YANG nodes | all "config true" data nodes 

| | | 
| How applied | changes automatically propagated to 

| | <operational> | 
| Protocols | NETCONF/RESTCONF (default) | 
| | | 
| Defining YANG | "example-ds-ephemeral" 

| module | | 
+-------------------- +—============================================= + 


Properties of the Example "ephemeral" Datastore 
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module example-ds-ephemeral { 
yang-version 1.1; 
namespace "urn:example:ds-ephemeral"; 
prefix eph; 


import ietf-datastores { 
prefix ds; 

} 

import ietf-origin { 
prefix or; 


} 


// datastore identity 
identity ds-ephemeral { 
base ds:dynamic; 
description 
"The ephemeral dynamic configuration datastore."; 


} 


// origin identity 
identity or-ephemeral { 
base or:dynamic; 
description 
"Denotes data from the ephemeral dynamic configuration 
datastore."; 


} 
Appendix C. Example Data 


The use of datastores is complex, and many of the subtle effects are 


more easily presented using examples. This section presents a series 
of example data models with some sample contents of the various 
datastores. 


The XML [W3C.REC-xml-20081126] snippets that follow are provided as 
examples only. 
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C.1. System Example 
In this example, the following fictional module is used: 


module example-system { 
yang-version 1.1; 
namespace urn:example:system; 
prefix sys; 


import ietf-inet-types { 
prefix inet; 


) 


container system ( 
leaf hostname { 
type string; 
} 


list interface { 
key name; 


leaf name { 
type string; 
} 


container auto-negotiation { 
leaf enabled { 
type boolean; 
default true; 
} 
leaf speed { 
type uint32; 
units mbps; 
description 
"The advertised speed, in Mbps."; 


} 


leaf speed { 
type uint32; 
units mbps; 
config false; 
description 
"The speed of the interface, in Mbps."; 
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list address { 
key ip; 


leaf ip { 
type inet:ip-address; 
} 
leaf prefix-length { 
type uint8; 
} 


} 


The operator has configured the hostname and two interfaces, so the 
contents of <intended> are: 


<system xmlns="urn:example:system"> 


<hostname>foo.example.com</hostname> 


<interface> 
<name>eth0</name> 
<auto-negotiation> 
<speed>1000</speed> 
</auto-negotiation> 
<address> 
<ip>2001:db8::10</ip> 
<prefix-length>64</prefix-length> 
</address> 
</interface> 


<interface> 
<name>ethl</name> 
<address> 
<ip>2001:db8::20</ip> 
<prefix-length>64</prefix-length> 
</address> 
</interface> 


</system> 


The system has detected that the hardware for one of the configured 


interfaces ("ethl") is not yet present, so the configuration for that 
interface is not applied. Further, the system has received a 
hostname and an additional IP address for "ethO" over DHCP. In 


addition to filling in the default value for the auto-negotiation 
enabled leaf, a loopback interface entry is also automatically 
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instantiated by the system. All of this is reflected in 
<operational>. Note how the "origin" metadata attribute for several 
"config true" data nodes is inherited from their parent data nodes. 


<system 
xmlns="urn:example:system" 
xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"> 


<hostname or:origin="or:learned">bar.example.com</hostname> 


<interface or:origin="or:intended"> 
<name>eth0</name> 
<auto-negotiation> 
<enabled or:origin="or:default">true</enabled> 
<speed>1000</speed> 
</auto-negotiation> 
<speed>100</speed> 
<address> 
<ip>2001:db8::10</ip> 
<prefix-length>64</prefix-length> 
</address> 
<address or:origin="or:learned"> 
<ip>2001:db8::1:100</ip> 
<prefix-length>64</prefix-length> 
</address> 
</interface> 


<interface or:origin="or:system"> 
<name>1o0</name> 
<address> 
<ip>::1</ip> 
<prefix-length>128</prefix-length> 
</address> 
</interface> 


</system> 
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C.2. BGP Example 
Consider the following fragment of a fictional BGP module: 


container bgp { 
leaf local-as { 
type uint32; 
} 
leaf peer-as { 
type uint32; 
} 
list peer { 
key name; 
leaf name { 
type inet:ip-address; 
} 
leaf local-as { 
type uint32; 
description 
"... Defaults to ../local-as."; 
} 
leaf peer-as { 
type uint32; 
description 
"... Defaults to ../peer-as."; 
} 
leaf local-port { 
type inet:port; 
} 
leaf remote-port { 
type inet:port; 
default 179; 
} 
leaf state { 
config false; 
type enumeration { 
enum init; 
enum established; 
enum closing; 


} 


} 


In this example model, both byp/peer/local-as and byp/peer/peer-as 
have complex hierarchical values, allowing the user to specify 
default values for all peers in a single location. 
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The model also follows the pattern of fully integrating state 
("config false") nodes with configuration ("config true") nodes. 
There is no separate "bgp-state" hierarchy, with the accompanying 
repetition of containment and naming nodes. This makes the model 
simpler and more readable. 


C.2.1. Datastores 


Each datastore represents differing views of these nodes. <running> 
will hold the configuration provided by the operator -- for example, 
a single BGP peer. <intended> will conceptually hold the data as 
validated, after the removal of data not intended for validation and 
after any local template mechanisms are performed. <operational> 
will show data from <intended> as well as any "config false" nodes. 


C.2.2. Adding a Peer 


If the user configures a single BGP peer, then that peer will be 
visible in both <running> and <intended>. It may also appear in 
<candidate> if the server supports the candidate configuration 
datastore. Retrieving the peer will return only the user-specified 
values. 


No time delay should exist between the appearance of the peer in 
<running> and <intended>. 


In this scenario, we’ve added the following to <running>: 


<bgp> 
<local-as>64501</local-as> 
<peer-as>64502</peer-as> 
<peer> 
<name>2001:db8::2:3</name> 
</peer> 
</bgp> 


C.2.2.1. <operational> 
The operational datastore will contain the fully expanded peer data, 
including "config false" nodes. In our example, this means that the 


"state" node will appear. 


In addition, <operational> will contain the "currently in use" values 


for all nodes. This means that local-as and peer-as will be 
populated even if they are not given values in <intended>. The value 
of bgp/local-as will be used if bgp/peer/local-as is not provided; 
bgp/peer-as and bgp/peer/peer-as will have the same relationship. In 
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the operational view, this means that every peer will have values for 
their local-as and peer-as, even if those values are not explicitly 
configured but are provided by bgp/local-as and bgp/peer-as. 


Each BGP peer has a TCP connection associated with it, using the 
values of local-port and remote-port from <intended>. If those 
values are not supplied, the system will select values. When the 
connection is established, <operational> will contain the current 
values for the local-port and remote-port nodes regardless of the 
origin. If the system has chosen the values, the "origin" attribute 
will be set to "System". Before the connection is established, one 
or both of the nodes may not appear, since the system may not yet 
have their values. 


<bgp xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" 
or:origin="or:intended"> 
<local-as>64501</local-as> 
<peer-as>64502</peer-as> 
<peer> 
<name>2001:db8::2:3</name> 
<local-as or:origin="or:default">64501</local-as> 
<peer-as or:origin="or:default">64502</peer-as> 
<local-port or:origin="or:system">60794</local-port> 
<remote-port or:origin="or:default">179</remote-port> 
<state>established</state> 
</peer> 
</bgp> 


C.2.3. Removing a Peer 


Changes to configuration may take time to percolate through the 
various software components involved. During this period, it is 
imperative to continue to give an accurate view of the working of the 
device. <operational> will contain nodes for both the previous and 
current configuration, as closely as possible tracking the current 
operation of the device. 


Consider the scenario where a client removes a BGP peer. When a peer 
is removed, the operational state will continue to reflect the 
existence of that peer until the peer’s resources are released, 
including closing the peer’s connection. During this period, the 
current data values will continue to be visible in <operational>, 
with the "origin" attribute set to indicate the origin of the 
original data. 
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<bgp xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" 
or:origin="or:intended"> 
<local-as>64501</local-as> 
<peer-as>64502</peer-as> 
<peer> 
<name>2001:db8::2:3</name> 
<local-as or:origin="or:default">64501</local-as> 
<peer-as or:origin="or:default">64502</peer-as> 
<local-port or:origin="or:system">60794</local-port> 
<remote-port or:origin="or:default">179</remote-port> 
<state>closing</state> 
</peer> 
</bgp> 


Once resources are released and the connection is closed, the peer’s 
data is removed from <operational>. 


C.3. Interface Example 


In this section, we will use this simple interface data model: 


container interfaces { 
list interface { 
key name; 
leaf name { 
type string; 
} 
leaf description { 
type string; 
} 
leaf mtu { 
type uint16; 
) 
leaf-list ip-address { 
type inet:ip-address; 


} 
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C.3.1. Pre-provisioned Interfaces 


One common issue in networking devices is the support of Field 
Replaceable Units (FRUs) that can be inserted and removed from the 
device without requiring a reboot or interfering with normal 
operation. These FRUs are typically interface cards, and the devices 
support pre-provisioning of these interfaces. 


If a client creates an interface "et-0/0/0" but the interface does 
not physically exist at this point, then <intended> might contain the 
following: 


<interfaces> 
<interface> 
<name>et-0/0/0</name> 
<description>Test interface</description> 
</interface> 
</interfaces> 


Since the interface does not exist, this data does not appear in 
<operational>. 


When a FRU containing this interface is inserted, the system will 
detect it and process the associated configuration. <operational> 
will contain the data from <intended>, as well as nodes added by the 
system, such as the current value of the interface’s MTU. 


<interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" 
or:origin="or:intended"> 
<interface> 
<name>et-0/0/0</name> 
<description>Test interface</description> 
<mtu or:origin="or:system">1500</mtu> 
</interface> 
</interfaces> 


If the FRU is removed, the interface data is removed from 
<operational>. 
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C.3.2. System-Provided Interface 


Imagine that the system provides a loopback interface (named "100") 
with a default IPv4 address of "127.0.0.1" and a default IPv6 address 
of "::1". The system will only provide configuration for this 
interface if there is no data for it in <intended>. 


When no configuration for "100" appears in <intended>, <operational> 
will show the system-provided data: 


<interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" 
or:origin="or:intended"> 
<interface or:origin="or:system"> 
<name>1lo0</name> 
<ip-address>127.0.0.1</ip-address> 
<ip-address>::1</ip-address> 
</interface> 
</interfaces> 


When configuration for "100" does appear in <intended>, <operational> 
will show that data with the origin set to "intended". If the 
"ip-address" is not provided, then the system-provided value will 
appear as follows: 


<interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" 
or:origin="or:intended"> 
<interface> 
<name>1lo0</name> 
<description>loopback</description> 
<ip-address or:origin="or:system">127.0.0.1</ip-address> 
<ip-address>::1</ip-address> 
</interface> 
</interfaces> 
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